Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

定位

全局 Location API 提供对设备地理位置信息的访问能力，包括一次性定位、逆地理编码、用户手动选点、定位精度控制、以及用于小组件的权限检测等功能。

功能概览

你可以通过该 API 实现以下功能：

  • 获取设备当前位置（支持缓存）
  • 用户通过地图界面手动选择位置
  • 将经纬度转换为可读的地址（逆地理编码）
  • 设置定位精度（耗电量和等待时间可控）
  • 检查小组件是否获得定位权限

注意： 该 API 为全局 API，无需额外导入。

接口文档

Location.isAuthorizedForWidgetUpdates(): Promise<boolean>

检查小组件是否拥有获取定位更新的权限。

1const isAuthorized = await Location.isAuthorizedForWidgetUpdates()
2if (!isAuthorized) {
3  console.log("小组件没有获取定位的权限")
4}

Location.setAccuracy(accuracy: LocationAccuracy): Promise<void>

设置期望的定位精度。精度越高，耗电和等待时间也可能增加。

可选值

精度值 描述
"best" 最高可用精度
"tenMeters" 10 米以内
"hundredMeters" 100 米以内
"kilometer" 1 公里以内
"threeKilometers" 3 公里以内 
1await Location.setAccuracy("hundredMeters")

Location.requestCurrent(options?: { forceRequest?: boolean }): Promise<LocationInfo | null>

请求一次设备当前的位置信息。

默认情况下，如果存在缓存位置（例如启动时从系统获取到的位置），将立即返回该缓存值。如果未缓存，则会触发新的定位请求。

你可以通过传入 { forceRequest: true } 强制跳过缓存，始终发起新请求。

参数

参数名 类型 是否必填 描述
forceRequest boolean 否 若为 true，将忽略缓存，始终发起新的定位请求。 
1const location = await Location.requestCurrent({ forceRequest: true })
2if (location) {
3  console.log("纬度:", location.latitude)
4  console.log("经度:", location.longitude)
5  console.log("时间戳:", location.timestamp)
6}

Location.pickFromMap(): Promise<LocationInfo | null>

打开内置地图界面，允许用户手动选择一个位置。

1const selected = await Location.pickFromMap()
2if (selected) {
3  console.log("用户选择的位置:", selected.latitude, selected.longitude)
4}

Location.reverseGeocode(options): Promise<LocationPlacemark[] | null>

将经纬度转换为人类可读的地理信息（如街道、城市、国家等）。

参数

字段 类型 是否必填 描述
latitude number 是 纬度（单位：度）
longitude number 是 经度（单位：度）
locale string 否 可选语言区域（如 "zh-CN"），默认使用设备语言设置 
1const placemarks = await Location.reverseGeocode({
2  latitude: 31.2304,
3  longitude: 121.4737,
4  locale: "zh-CN"
5})
6
7if (placemarks?.length) {
8  const place = placemarks[0]
9  console.log("城市:", place.locality)
10  console.log("国家:", place.country)
11}

类型定义

LocationAccuracy

表示定位精度选项：

1type LocationAccuracy =
2  | "best"
3  | "tenMeters"
4  | "hundredMeters"
5  | "kilometer"
6  | "threeKilometers"

LocationInfo

表示一个带有时间戳的地理坐标点：

1type LocationInfo = {
2  /**
3   * 纬度，单位：度
4   */
5  latitude: number
6  /**
7   * 经度，单位：度
8   */
9  longitude: number
10  /**
11   * 获取该位置的时间戳（单位：毫秒）
12   */
13  timestamp: number
14}

LocationPlacemark

表示一个可读的地理位置，通常由逆地理编码返回，包含详细的地址结构信息：

1type LocationPlacemark = {
2  location?: LocationInfo
3  region?: string
4  timeZone?: string
5  name?: string
6  thoroughfare?: string
7  subThoroughfare?: string
8  locality?: string
9  subLocality?: string
10  administrativeArea?: string
11  subAdministrativeArea?: string
12  postalCode?: string
13  isoCountryCode?: string
14  country?: string
15  inlandWater?: string
16  ocean?: string
17  areasOfInterest?: string[]
18}

字段说明

字段 类型 描述
location LocationInfo 坐标点信息（通常等于请求的经纬度）
region string 区域名，如省/州
timeZone string 时区标识（如 "Asia/Shanghai"）
name string 地点名称，如建筑物、地标等
thoroughfare string 街道名称，如 "中关村大街"
subThoroughfare string 详细地址，如门牌号
locality string 城市或镇
subLocality string 区、街道等子区域
administrativeArea string 省份、州或其他一级行政区域
subAdministrativeArea string 县、区等次级行政区域
postalCode string 邮政编码
isoCountryCode string 国家代码（ISO 3166-1 alpha-2，如 "CN"）
country string 国家全名，如 "中国"
inlandWater string 附近的内陆水体名称，如湖泊、河流
ocean string 附近的海洋名称
areasOfInterest string[] 附近的兴趣点/地标数组，如 "东方明珠"

示例用法

逆地理编码

1const placemarks = await Location.reverseGeocode({
2  latitude: 39.9042,
3  longitude: 116.4074,
4  locale: "zh-CN"
5})
6
7if (placemarks?.length) {
8  const place = placemarks[0]
9  console.log("国家:", place.country)
10  console.log("城市:", place.locality)
11  console.log("街道:", place.thoroughfare, place.subThoroughfare)
12  console.log("地标名称:", place.name)
13  console.log("邮编:", place.postalCode)
14  console.log("兴趣点:", place.areasOfInterest?.join(", "))
15}

地址格式化工具

1function formatAddress(p: LocationPlacemark): string {
2  return [
3    p.country,
4    p.administrativeArea,
5    p.locality,
6    p.subLocality,
7    p.thoroughfare,
8    p.subThoroughfare
9  ].filter(Boolean).join(", ")
10}

最佳实践与使用建议

  • 使用 areasOfInterest 和 name 显示更友好的位置信息（如地标名）
  • 使用 postalCode、locality、administrativeArea 自动填写表单或记录标签
  • 使用 timestamp 判断位置数据是否新鲜
  • 使用 timeZone 进行本地时间转换或事件提醒
  • 在调用 requestCurrent 前使用 setAccuracy 控制精度
  • 对小组件使用 isAuthorizedForWidgetUpdates() 检查权限

说明

  • 逆地理编码可能返回多个结果，通常第一个最相关
  • 若获取失败，API 将返回 null
  • 若未强制刷新，系统会优先使用缓存位置，响应更快
  • 小组件受限于系统权限机制，务必检测权限状态
大纲